home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / glibmm-2.4 / glibmm / miscutils.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-04-20  |  11.1 KB  |  273 lines
  1. // -*- c++ -*-
  2. #ifndef _GLIBMM_MISCUTILS_H
  3. #define _GLIBMM_MISCUTILS_H
  4.  
  5. /* $Id: miscutils.h,v 1.4 2005/06/07 06:32:45 gustin Exp $ */
  6.  
  7. /* Copyright (C) 2002 The gtkmm Development Team
  8.  *
  9.  * This library is free software; you can redistribute it and/or
  10.  * modify it under the terms of the GNU Library General Public
  11.  * License as published by the Free Software Foundation; either
  12.  * version 2 of the License, or (at your option) any later version.
  13.  *
  14.  * This library is distributed in the hope that it will be useful,
  15.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17.  * Library General Public License for more details.
  18.  *
  19.  * You should have received a copy of the GNU Library General Public
  20.  * License along with this library; if not, write to the Free
  21.  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  22.  */
  23.  
  24. #include <glibmm/arrayhandle.h>
  25. #include <glibmm/ustring.h>
  26.  
  27.  
  28. namespace Glib
  29. {
  30.  
  31. /** @defgroup MiscUtils Miscellaneous Utility Functions
  32.  * Miscellaneous Utility Functions -- a selection of portable utility functions.
  33.  * @{
  34.  */
  35.  
  36. /** Gets a human-readable name for the application,
  37.  * as set by Glib::set_application_name().
  38.  * This name should be localized if possible, and is intended for display to
  39.  * the user.  Contrast with Glib::get_prgname(), which gets a non-localized
  40.  * name. If Glib::set_application_name() has not been called, returns the
  41.  * result of Glib::get_prgname() (which may be empty if Glib::set_prgname()
  42.  * has also not been called).
  43.  *
  44.  * @return Human-readable application name. May return <tt>""</tt>.
  45.  */
  46. Glib::ustring get_application_name();
  47.  
  48. /** Sets a human-readable name for the application.
  49.  * This name should be localized if possible, and is intended for display to
  50.  * the user.  Contrast with Glib::set_prgname(), which sets a non-localized
  51.  * name.  Glib::set_prgname() will be called automatically by
  52.  * <tt>gtk_init()</tt>, but Glib::set_application_name() will not.
  53.  *
  54.  * Note that for thread safety reasons, this function can only be called once.
  55.  *
  56.  * The application name will be used in contexts such as error messages,
  57.  * or when displaying an application's name in the task list.
  58.  *
  59.  * @param application_name Localized name of the application.
  60.  */
  61. void set_application_name(const Glib::ustring& application_name);
  62.  
  63. /** Gets the name of the program.
  64.  * If you are using GDK or GTK+ the program name is set in <tt>gdk_init()</tt>,
  65.  * which is called by <tt>gtk_init()</tt>.  The program name is found by taking
  66.  * the last component of <tt>argv[0]</tt>.
  67.  * @return The name of the program.
  68.  */
  69. std::string get_prgname();
  70.  
  71. /** Sets the name of the program.
  72.  * @param prgname The name of the program.
  73.  */
  74. void set_prgname(const std::string& prgname);
  75.  
  76. /** Returns the value of an environment variable. The name and value
  77.  * are in the GLib file name encoding. On Unix, this means the actual
  78.  * bytes which might or might not be in some consistent character set
  79.  * and encoding. On Windows, it is in UTF-8. On Windows, in case the
  80.  * environment variable's value contains references to other
  81.  * environment variables, they are expanded.
  82.  *
  83.  * @param variable The environment variable to get.
  84.  * @retval found <tt>true</tt> Whether the environment variable has been found.
  85.  * @return The value of the environment variable, or <tt>""</tt> if not found.
  86.  */
  87. std::string getenv(const std::string& variable, bool& found);
  88.  
  89. /** Returns the value of an environment variable. The name and value
  90.  * are in the GLib file name encoding. On Unix, this means the actual
  91.  * bytes which might or might not be in some consistent character set
  92.  * and encoding. On Windows, it is in UTF-8. On Windows, in case the
  93.  * environment variable's value contains references to other
  94.  * environment variables, they are expanded.
  95.  *
  96.  * @param variable The environment variable to get.
  97.  * @return The value of the environment variable, or <tt>""</tt> if not found.
  98.  */
  99. std::string getenv(const std::string& variable);
  100.  
  101.  
  102. /** Sets an environment variable. Both the variable's name and value
  103.  * should be in the GLib file name encoding. On Unix, this means that
  104.  * they can be any sequence of bytes. On Windows, they should be in
  105.  * UTF-8.
  106.  *
  107.  * Note that on some systems, when variables are overwritten, the memory 
  108.  * used for the previous variables and its value isn't reclaimed.
  109.  *
  110.  * @param variable The environment variable to set. It must not contain '='.
  111.  * @param value  The value to which the variable should be set.
  112.  * @param overwrite Whether to change the variable if it already exists.
  113.  * @result false if the environment variable couldn't be set.
  114.  */ 
  115. bool setenv(const std::string& variable, const std::string& value, bool overwrite = true);
  116.  
  117. /** Removes an environment variable from the environment.
  118.  *
  119.  * Note that on some systems, when variables are overwritten, the memory 
  120.  * used for the previous variables and its value isn't reclaimed.
  121.  * Furthermore, this function can't be guaranteed to operate in a 
  122.  * threadsafe way.
  123.  *
  124.  * @param variable: the environment variable to remove. It  must not contain '='.
  125.  **/
  126. void unsetenv(const std::string& variable);
  127.  
  128. /** Gets the user name of the current user.
  129.  * @return The name of the current user.
  130.  */
  131. std::string get_user_name();
  132.  
  133. /** Gets the real name of the user.
  134.  * This usually comes from the user's entry in the <tt>passwd</tt> file.
  135.  * @return The user's real name.
  136.  */
  137. std::string get_real_name();
  138.  
  139. /** Gets the current user's home directory.
  140.  * @return The current user's home directory or an empty string if not defined.
  141.  */
  142. std::string get_home_dir();
  143.  
  144. /** Gets the directory to use for temporary files.
  145.  * This is found from inspecting the environment variables <tt>TMPDIR</tt>,
  146.  * <tt>TMP</tt>, and <tt>TEMP</tt> in that order.  If none of those are defined
  147.  * <tt>"/tmp"</tt> is returned on UNIX and <tt>"C:\\"</tt> on Windows.
  148.  * @return The directory to use for temporary files.
  149.  */
  150. std::string get_tmp_dir();
  151.  
  152. /** Gets the current directory.
  153.  * @return The current directory.
  154.  */
  155. std::string get_current_dir();
  156.  
  157. /** Returns @c true if the given @a filename is an absolute file name, i.e.\ it
  158.  * contains a full path from the root directory such as <tt>"/usr/local"</tt>
  159.  * on UNIX or <tt>"C:\\windows"</tt> on Windows systems.
  160.  * @param filename A file name.
  161.  * @return Whether @a filename is an absolute path.
  162.  */
  163. bool path_is_absolute(const std::string& filename);
  164.  
  165. /** Returns the remaining part of @a filename after the root component,
  166.  * i.e.\ after the <tt>"/"</tt> on UNIX or <tt>"C:\\"</tt> on Windows.
  167.  * If @a filename is not an absolute path, <tt>""</tt> will be returned.
  168.  * @param filename A file name.
  169.  * @return The file name without the root component, or <tt>""</tt>.
  170.  */
  171. std::string path_skip_root(const std::string& filename);
  172.  
  173. /** Gets the name of the file without any leading directory components.
  174.  * @param filename The name of the file.
  175.  * @return The name of the file without any leading directory components.
  176.  */
  177. std::string path_get_basename(const std::string& filename);
  178.  
  179. /** Gets the directory components of a file name.
  180.  * If the file name has no directory components <tt>"."</tt> is returned.
  181.  * @param filename The name of the file.
  182.  * @return The directory components of the file.
  183.  */
  184. std::string path_get_dirname(const std::string& filename);
  185.  
  186. /** Creates a filename from a series of elements using the correct
  187.  * separator for filenames.
  188.  * This function behaves identically to Glib::build_path(G_DIR_SEPARATOR_S,
  189.  * elements).  No attempt is made to force the resulting filename to be an
  190.  * absolute path.  If the first element is a relative path, the result will
  191.  * be a relative path.
  192.  * @param elements A container holding the elements of the path to build.
  193.  *   Any STL compatible container type is accepted.
  194.  * @return The resulting path.
  195.  */
  196. std::string build_filename(const Glib::ArrayHandle<std::string>& elements);
  197.  
  198. /** Creates a filename from two elements using the correct separator for filenames.
  199.  * No attempt is made to force the resulting filename to be an absolute path.
  200.  * If the first element is a relative path, the result will be a relative path.
  201.  * @param elem1 First path element.
  202.  * @param elem2 Second path element.
  203.  * @return The resulting path.
  204.  */
  205. std::string build_filename(const std::string& elem1, const std::string& elem2);
  206.  
  207. /** Creates a path from a series of elements using @a separator as the
  208.  * separator between elements.
  209.  *
  210.  * At the boundary between two elements, any trailing occurrences of
  211.  * @a separator in the first element, or leading occurrences of @a separator
  212.  * in the second element are removed and exactly one copy of the separator is
  213.  * inserted.
  214.  *
  215.  * Empty elements are ignored.
  216.  *
  217.  * The number of leading copies of the separator on the result is
  218.  * the same as the number of leading copies of the separator on
  219.  * the first non-empty element.
  220.  *
  221.  * The number of trailing copies of the separator on the result is the same
  222.  * as the number of trailing copies of the separator on the last non-empty
  223.  * element. (Determination of the number of trailing copies is done without
  224.  * stripping leading copies, so if the separator is <tt>"ABA"</tt>,
  225.  * <tt>"ABABA"</tt> has 1 trailing copy.)
  226.  *
  227.  * However, if there is only a single non-empty element, and there
  228.  * are no characters in that element not part of the leading or
  229.  * trailing separators, then the result is exactly the original value
  230.  * of that element.
  231.  *
  232.  * Other than for determination of the number of leading and trailing
  233.  * copies of the separator, elements consisting only of copies
  234.  * of the separator are ignored.
  235.  *                                                                             
  236.  * @param separator A string used to separate the elements of the path.
  237.  * @param elements A container holding the elements of the path to build.
  238.  *   Any STL compatible container type is accepted.
  239.  * @return The resulting path.
  240.  */
  241. std::string build_path(const std::string& separator,
  242.                        const Glib::ArrayHandle<std::string>& elements);
  243.  
  244. /** Locates the first executable named @a program in the user's path, in the
  245.  * same way that <tt>execvp()</tt> would locate it.
  246.  * Returns a string with the absolute path name, or <tt>""</tt> if the program
  247.  * is not found in the path.  If @a program is already an absolute path,
  248.  * returns a copy of @a program if @a program exists and is executable, and
  249.  * <tt>""</tt> otherwise.
  250.  *
  251.  * On Windows, if @a program does not have a file type suffix, tries to append
  252.  * the suffixes in the <tt>PATHEXT</tt> environment variable (if that doesn't
  253.  * exist, the suffixes .com, .exe, and .bat) in turn, and then look for the
  254.  * resulting file name in the same way as CreateProcess() would.  This means
  255.  * first in the directory where the program was loaded from, then in the
  256.  * current directory, then in the Windows 32-bit system directory, then in the
  257.  * Windows directory, and finally in the directories in the <tt>PATH</tt>
  258.  * environment variable.  If the program is found, the return value contains
  259.  * the full name including the type suffix.
  260.  *
  261.  * @param program A program name.
  262.  * @return An absolute path, or <tt>""</tt>.
  263.  */
  264. std::string find_program_in_path(const std::string& program);
  265.  
  266. /** @} group MiscUtils */
  267.  
  268. } // namespace Glib
  269.  
  270.  
  271. #endif /* _GLIBMM_FILEUTILS_H */
  272.  
  273.